/**
 * Copyright 2011 Andreas Kaubisch
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 **/
package de.easymessage;

public interface MessageService {
	
	/**
	 * Creates an Channel if necessary and add a {@link ChannelListener} to it. A channel can have one or
	 * more listeners assigned to it. So if a channel publish a message all listeners will be notified.
	 * If no channel with the name exists the service generate a new one.
	 * 
	 * @param channelName the name of a channel where the listener should be listening
	 * @param listener this listener needs to be registered with the channel
	 * 
	 * @throws IllegalArgumentException It throws an Exception if the listener isn't be set or the name of
	 * 									the channel is empty.
	 */
	public void subscribe(String channelName, ChannelListener<?> listener);

	/**
	 * Remove the listener from all channels so that it can't receive any message anymore.
	 * 
	 * @param listener this listener must be removed from all channels
	 * 
	 * @throws IllegalArgumentException It throws an Exception if the listener isn't be set
	 */
	public void unsubscribe(ChannelListener<?> listener);

	/**
	 * Publish a message to a given channel if it exists. All listeners that are registered to that channel
	 * will be notified by the service.
	 * 
	 * @param channelName the name of a channel where the listener should be listening
	 * @param message the message that must be send to the given channel.
	 * 
	 * @throws IllegalArgumentException It throws an Exception if the name of the channel is empty.
	 */
	public void publish(String channelName, ChannelMessage<?> message);
}
